MarkLogic 10 Product Documentation

PUT /v1/config/query/(default|{name})/{child-element}

Summary

Replace options in existing named query options, or create new named query options if {name} does not already exist.

Response

Upon success, MarkLogic Server responds with status 201 (Created) or 204 (Updated).

If the payload is invalid or applying the payload results in invalid query options, MarkLogic Server responds with status 400 (Bad Request) by default. Options validation can be disabled. For details, see see the validate-options in Instance Configuration Properties in the REST Application Developer's Guide.

Required Privileges

http://marklogic.com/xdmp/privileges/rest-admin

http://marklogic.com/xdmp/privileges/rest-writer

http://marklogic.com/xdmp/privileges/rest-reader

Usage Notes

The request payload should be a valid search:options node, expressed in either XML or JSON, depending upon the request Content-Type header or format parameter. For a summary of available options, see PUT /v1/config/query/(default|{name}). For details, see Appendix: Query Options Reference in the Search Developer's Guide.

If no query options are installed under {name}, they are created. If the named query options exist, the options in the request body replace all existing option elements with the same name. For example, if the query options contains three <constraint/> options and the request body includes only one <constraint/>, the three existing constraints are removed and replaced with the one in the request body.

If options validation is enabled (the default) and the new options would result in invalid query options, the query options remain unchanged, and a 400 status is returned. Options validation can be disabled. For details, see validate-options in Instance Configuration Properties in the REST Application Developer's Guide.

The request body can contain multiple option elements (settings) if {child-element} is an element that can occur multiple times in query options. For example, multiple search constraints (<constraint/>) can be set in a single request. However, all options in the payload must be of the same type.

If the named query options do not exist, create new named query options. If the named query options exist, the options in the request body replace any existing options of the same name. For example, if the query options contains 3 constraint options and the PUT request includes only one constraint, all 3 constraints are removed and replaced with the single constraint from the request.

If {name} is default, the default search options are modified.

For more details, see Configuring Query Options in the REST Application Developer's Guide.

Example

$ cat added-constraint.xml
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="title">
    <word>
      <element ns="" name="TITLE" />
    </word>
  </constraint>
</options>

$ curl --anyauth --user user:password -i -X PUT -d@"added-constraint.xml" \
    -H "Content-type: application/xml" \
    http://localhost:8000/v1/config/query/my-options/constraint

==> The "title" constraint is added to the "my-options" query options. If
    the query options already contain other <constraint/> elements, they 
    are removed.  MarkLogic Server returns the following headers:

HTTP/1.1 204 Updated
Location:
Server: MarkLogic
Content-Length: 0
Connection: close
  

Example

$ cat added-constraint.json
{ "options": {
    "constraint": [ {
        "name": "title",
        "word": {
          "element": {
            "ns": "",
            "name": "TITLE"
          }
        }
    } ]
} }

$ curl --anyauth --user user:password -i -X PUT -d@"added-constraint.json" \
    -H "Content-type: application/json" \
    http://localhost:8000/v1/config/query/my-options/constraint

==> The "title" constraint is added to the "my-options" query options. If
    the query options already contain other <constraint/> elements, they 
    are removed.  MarkLogic Server returns the following headers:

HTTP/1.1 204 Updated
Location:
Server: MarkLogic
Content-Length: 0
Connection: close